<!-- HTML header for doxygen 1.8.18-->
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.9.8"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>Ipopt: Special Features</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
  $(document).ready(function() { init_search(); });
/* @license-end */
</script>
<script type="text/x-mathjax-config">
MathJax.Hub.Config({
  extensions: ["tex2jax.js"],
  jax: ["input/TeX","output/HTML-CSS"],
});
</script>
<script type="text/javascript" async="async" src="https://cdn.jsdelivr.net/npm/mathjax@2/MathJax.js"></script>
<link href="stylesheet.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 40px;">
  <td id="projectalign" style="padding-left: 0.5em;">
   <div id="projectname">Ipopt Documentation
   &#160;<!--span id="projectnumber">3.14.15</span-->
   </div>
  </td>
   <td>        <div id="MSearchBox" class="MSearchBoxInactive">
        <span class="left">
          <span id="MSearchSelect"                onmouseover="return searchBox.OnSearchSelectShow()"                onmouseout="return searchBox.OnSearchSelectHide()">&#160;</span>
          <input type="text" id="MSearchField" value="" placeholder="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)" 
               onblur="searchBox.OnSearchFieldFocus(false)" 
               onkeyup="searchBox.OnSearchFieldChange(event)"/>
          </span><span class="right">
            <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.svg" alt=""/></a>
          </span>
        </div>
</td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.9.8 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
var searchBox = new SearchBox("searchBox", "search/",'.html');
/* @license-end */
</script>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
      <div id="nav-sync" class="sync"></div>
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(document).ready(function(){initNavTree('SPECIALS.html',''); initResizable(); });
/* @license-end */
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<div id="MSearchResults">
<div class="SRPage">
<div id="SRIndex">
<div id="SRResults"></div>
<div class="SRStatus" id="Loading">Loading...</div>
<div class="SRStatus" id="Searching">Searching...</div>
<div class="SRStatus" id="NoMatches">No Matches</div>
</div>
</div>
</div>
</div>

<div><div class="header">
  <div class="headertitle"><div class="title">Special Features</div></div>
</div><!--header-->
<div class="contents">
<div class="toc"><h3>Table of Contents</h3>
<ul><li class="level1"><a href="#DERIVCHECK">Derivative Checker</a></li>
<li class="level1"><a href="#QUASI_NEWTON">Quasi-Newton Approximation of Second Derivatives</a></li>
<li class="level1"><a href="#AMPL_WARMSTART">Warm-Starting Capabilities via AMPL</a></li>
<li class="level1"><a href="#SIPOPT">sIpopt: Optimal Sensitivity Based on Ipopt</a></li>
<li class="level1"><a href="#INERTIAFREE_CURVTEST">Inertia-Free Curvature Test</a></li>
</ul>
</div>
<div class="textblock"><h1><a class="anchor" id="DERIVCHECK"></a>
Derivative Checker</h1>
<p>When writing code for the evaluation of derivatives it is very easy to make mistakes (much easier than writing it correctly the first time :)). As a convenient feature, Ipopt provides the option to run a simple derivative checker, based on finite differences, before the optimization is started.</p>
<p>To use the derivative checker, you need to use the option <a class="el" href="OPTIONS.html#OPT_derivative_test">derivative_test</a>. By default, this option is set to <code>none</code>, i.e., no finite difference test is performed. If it is set to <code>first-order</code>, then the first derivatives of the objective function and the constraints are verified, and for the setting <code>second-order</code>, the second derivatives are tested as well.</p>
<p>The verification is done by a simple finite differences approximation, where each component of the user-provided starting point is perturbed one of the other. The relative size of the perturbation is determined by the option <a class="el" href="OPTIONS.html#OPT_derivative_test_perturbation">derivative_test_perturbation</a>. The default value (10<sup>-8</sup>, about the square root of the machine precision) is probably fine in most cases, but if you believe that you see wrong warnings, you might want to play with this parameter. When the test is performed, Ipopt prints out a line for every partial derivative, for which the user-provided derivative value deviates too much from the finite difference approximation. The relative tolerance for deciding when a warning should be issued, is determined by the option <a class="el" href="OPTIONS.html#OPT_derivative_test_tol">derivative_test_tol</a>. If you want to see the user-provided and estimated derivative values with the relative deviation for each single partial derivative, you can switch the option <a class="el" href="OPTIONS.html#OPT_derivative_test_print_all">derivative_test_print_all</a> to <code>yes</code>.</p>
<p>A typical output is: </p><pre class="fragment">Starting derivative checker.

* grad_f[          2] = -6.5159999999999991e+02    ~ -6.5559997134793468e+02  [ 6.101e-03]
* jac_g [    4,    4] =  0.0000000000000000e+00    ~  2.2160643690464592e-02  [ 2.216e-02]
* jac_g [    4,    5] =  1.3798494268463347e+01 v  ~  1.3776333629422766e+01  [ 1.609e-03]
* jac_g [    6,    7] =  1.4776333636790881e+01 v  ~  1.3776333629422766e+01  [ 7.259e-02]

Derivative checker detected 4 error(s).
</pre><p>The star ("*") in the first column indicates that this line corresponds to some partial derivative for which the error tolerance was exceeded. Next, we see which partial derivative is concerned in this output line. For example, in the first line, it is the second component of the objective function gradient (or the third, if the C_STYLE numbering is used, i.e., when counting of indices starts with 0 instead of 1). The first floating point number is the value given by the user code, and the second number (after "~") is the finite differences estimation. Finally, the number in square brackets is the relative difference between these two numbers \(\left(\frac{|\mathrm{approx}-\mathrm{exact}|}{\max(|\mathrm{approx}|,\mathrm{derivative\_test\_tol})}\right)\).</p>
<p>For constraints, the first index after <code>jac_g</code> is the index of the constraint, and the second one corresponds to the variable index (again, the choice of the numbering style matters).</p>
<p>Since also the sparsity structure of the constraint Jacobian has to be provided by the user, it can be faulty as well. For this, the "v" after a user-provided derivative value indicates that this component of the Jacobian is part of the user provided sparsity structure. If there is no "v", it means that the user did not include this partial derivative in the list of non-zero elements. In the above output, the partial derivative <code>jac_g[4,4]</code> is non-zero (based on the finite difference approximation), but it is not included in the list of non-zero elements (missing "v"), so that the user probably made a mistake in the sparsity structure. The other two Jacobian entries are provided in the non-zero structure but their values seem to be off.</p>
<p>For second derivatives, the output looks like: </p><pre class="fragment">*             obj_hess[    1,    1] =  1.8810000000000000e+03 v  ~  1.8820000036612328e+03  [ 5.314e-04]
*     3-th constr_hess[    2,    4] =  1.0000000000000000e+00 v  ~  0.0000000000000000e+00  [ 1.000e+00]
</pre><p> There, the first line shows the deviation of the user-provided partial second derivative in the Hessian for the objective function, and the second line show an error in a partial derivative for the Hessian of the third constraint (again, the numbering style matters).</p>
<p>Since the second derivatives are approximates by finite differences of the first derivatives, you should first correct errors for the first derivatives. Also, since the finite difference approximations are quite expensive, you should try to debug a small instance of your problem if you can.</p>
<p>Another useful option is <a class="el" href="OPTIONS.html#OPT_derivative_test_first_index">derivative_test_first_index</a> which allows your to start the derivative test with variables with a larger index. Finally, it is of course always a good idea to run your code through some memory checker, such as valgrind on Linux.</p>
<h1><a class="anchor" id="QUASI_NEWTON"></a>
Quasi-Newton Approximation of Second Derivatives</h1>
<p>Ipopt has an option to approximate the Hessian of the Lagrangian by a limited-memory quasi-Newton method (L-BFGS). You can use this feature by setting the option <a class="el" href="OPTIONS.html#OPT_hessian_approximation">hessian_approximation</a> to the value <code>limited-memory</code>. In this case, it is not necessary to implement the Hessian computation method <a class="el" href="classIpopt_1_1TNLP.html#a26b9145267e2574c53acc284fef1c354" title="Method to request either the sparsity structure or the values of the Hessian of the Lagrangian.">Ipopt::TNLP::eval_h</a>. If you are using the C or Fortran interface, you still need to implement these functions, but they should return <code>false</code> or <code>IERR=1</code>, respectively, and don't need to do anything else.</p>
<p>In general, when second derivatives can be computed with reasonable computational effort, it is usually a good idea to use them, since then Ipopt normally converges in fewer iterations and is more robust. An exception might be in cases, where your optimization problem has a dense Hessian, i.e., a large percentage of non-zero entries in the Hessian. In such a case, using the quasi-Newton approximation might be better, even if it increases the number of iterations, since with exact second derivatives the computation time per iteration might be significantly higher due to the very large number of non-zero elements in the linear systems that Ipopt solve in order to compute the search direction.</p>
<p>Since the Hessian of the Lagrangian is zero for all variables that appear only linearly in the objective and constraint functions, the Hessian approximation should only take place in the space of all nonlinear variables. By default, it is assumed that all variables are nonlinear, but you can tell Ipopt explicitly which variables are nonlinear, using the <a class="el" href="classIpopt_1_1TNLP.html#a015506564afc611060f4416dbb08aa4d" title="Return the number of variables that appear nonlinearly in the objective function or in at least one c...">Ipopt::TNLP::get_number_of_nonlinear_variables</a> and <a class="el" href="classIpopt_1_1TNLP.html#a9bb5f16cdc2754d1667749268fb1308c" title="Return the indices of all nonlinear variables.">Ipopt::TNLP::get_list_of_nonlinear_variables</a> methods, see <a class="el" href="INTERFACES.html#INTERFACE_CPP_ADDITIONAL">Additional methods in TNLP</a>. (Those methods have been implemented for the AMPL interface, so you would automatically only approximate the Hessian in the space of the nonlinear variables, if you are using the quasi-Newton option for AMPL models.) Currently, those two methods are not available through the C or Fortran interface.</p>
<h1><a class="anchor" id="AMPL_WARMSTART"></a>
Warm-Starting Capabilities via AMPL</h1>
<p>This section is based on documentation by Victor M. Zavala (Department of Chemical Engineering, Carnegie Mellon University).</p>
<p>Warm-starting an interior-point algorithm is an important issue. One of the main difficulties arises from the fact that full-space variable information is required to generate the warm-starting point. While Ipopt is currently equipped to retrieve and receive this type of information through the TNLP interface, there exist some communication barriers in the AMPL interface. When the user solves the problem <a class="el" href="index.html#NLP">(NLP)</a>, Ipopt will only return the optimal values of the primal variables \(x\) and of the constraint multipliers corresponding to the active sides of \(g^L \leq g(x) \leq g^U\). The constraint multiplier values can be accessed through the <code>.dual</code> suffix or through the <code>.sol</code> file. If this information is used to solve the same problem again, you will notice that Ipopt will take some iterations in finding the same solution. The reason for this is that we are missing the input information of the multipliers \(z^L\) and \(z^U\) corresponding to the variable bounds \(x^L \leq x \leq x^U\).</p>
<p>However, Ipopt also passes the values of the bound multipliers \(z^L\) and \(z^U\) to AMPL. This will be communicated to the AMPL user through the suffixes <code>ipopt_zL_out</code> and <code>ipopt_zU_out</code>, respectively. The user does not need to declare these suffixes, they will be generated automatically in the AMPL interface. The user can use the suffix values to initialize the bound multipliers for subsequent calls. In order to pass this information to Ipopt, the user will need to declare and assign values to the suffixes <code>ipopt_zL_in</code> and <code>ipopt_zU_in</code>. For instance, for a given variable <code>x[i]</code>, this can be done by setting: </p><pre class="fragment">let x[i].ipopt_zL_in := x[i].ipopt_zL_out;
let x[i].ipopt_zU_in := x[i].ipopt_zU_out;
</pre><p>If the user does not specify some of these values, Ipopt will set these multipliers to 1.0 (as before). In order to make the warm-start effective, the user has control over the following options from AMPL:</p><ul>
<li><a class="el" href="OPTIONS.html#OPT_warm_start_init_point">warm_start_init_point</a></li>
<li><a class="el" href="OPTIONS.html#OPT_warm_start_bound_push">warm_start_bound_push</a></li>
<li><a class="el" href="OPTIONS.html#OPT_warm_start_mult_bound_push">warm_start_mult_bound_push</a></li>
</ul>
<p>Note, that the use of this feature is far from solving the complicated issue of warm-starting interior-point algorithms. As a general advice, this feature will be useful if the user observes that the solution of subsequent problems (i.e., for different data instances) preserves the same set of active inequalities and bounds (monitor the values of \(z^L\) and \(z^U\) for subsequent solutions). In this case, initializing the bound multipliers and setting <code>warm_start_init_point</code> to <code>yes</code> and setting <code>warm_start_bound_push</code>, <code>warm_start_mult_bound_push</code>, and <code>mu_init</code> to a small value (10<sup>-6</sup> or so) will reduce significantly the number of iterations. This is particularly useful in setting up on-line applications and high-level optimization strategies in AMPL. If active-set changes are observed between subsequent solutions, then this strategy might not decrease the number of iterations (in some cases, it might even tend to increase the number of iterations).</p>
<p>You might also want to try the adaptive barrier update (instead of the default monotone one where above we chose the initial value 10<sup>-6</sup>) when doing the warm start. This can be activated by setting the option <a class="el" href="OPTIONS.html#OPT_mu_strategy">mu_strategy</a> to <code>adaptive</code>. Also the option <a class="el" href="OPTIONS.html#OPT_mu_oracle">mu_oracle</a> gives some alternative choices. In general, the adaptive choice often leads to less iterations, but the computational cost per iteration might be higher.</p>
<p>The file <code>$IPOPTDIR/Ipopt/doc/hs071_warmstart.mod</code> illustrates the use of the warm-start feature on the HS071 problem, see also <a class="el" href="INTERFACES.html#INTERFACE_AMPL">Using Ipopt through AMPL</a>.</p>
<h1><a class="anchor" id="SIPOPT"></a>
sIpopt: Optimal Sensitivity Based on Ipopt</h1>
<p>This section is based on documentation by Hans Pirnay (RWTH Aachen) and Rodrigo López-Negrete (Carnegie Mellon University).</p>
<p>The <code>sIpopt</code> project provides a toolbox that uses NLP sensitivity theory to generate fast approximations to solutions when parameters in the problem change. It has been developed primarily by Hans Pirnay (RWTH-Aachen), Rodrigo López-Negrete (CMU), and Lorenz Biegler (CMU).</p>
<p>Sensitivity of nonlinear programming problems is a key step in any optimization study. Sensitivity provides information on regularity and curvature conditions at KKT points, assesses which variables play dominant roles in the optimization, and provides first order estimates for parametric nonlinear programs. Moreover, for NLP algorithms that use exact second derivatives, sensitivity can be implemented very efficiently within NLP solvers and provide valuable information with very little added computation. This implementation provides Ipopt with the capabilities to calculate sensitivities, and approximate perturbed solutions with them.</p>
<p>The basic sensitivity strategy implemented here is based on the application of the Implicit Function Theorem (IFT) to the KKT conditions of the NLP. As shown by Fiacco <a class="el" href="citelist.html#CITEREF_Fiacco1983">[4]</a>, sensitivities can be obtained from a solution with suitable regularity conditions merely by solving a linearization of the KKT conditions. More details can be found in <a class="el" href="citelist.html#CITEREF_PLNB:sIpopt">[8]</a>. If you are using <code>sIpopt</code> for your research, please cite <a class="el" href="citelist.html#CITEREF_PLNB:sIpopt">[8]</a>.</p>
<p>The <code>sIpopt</code> project is available in the Ipopt repository under <code>$IPOPTDIR/contrib/sIPOPT</code>. It is build together with the Ipopt library and the generated library <code>libsipopt.*</code> and AMPL executable <code>ipopt_sens</code> are installed in <code>$PREFIX/lib</code> and <code>$PREFIX/bin</code>.</p>
<p>The files <code>$IPOPTDIR/contrib/sIPOPT/examples/parametric_ampl/parametric.{mod,run}</code> are an example that shows how to use <code>sIpopt</code> to solve the NLP  </p><p class="formulaDsp">
\begin{align*}
\min\quad &amp; x_1^2 + x_2^2 + x_3^2, \\
\text{such that}\quad &amp; 6x_1 + 3x_2 + 2x_3 = p_1, \\
 &amp; p_2 x_1 + x_2 - x_3  = 1, \\
 &amp; x_1, x_2, x_3 \geq 0,
\end{align*}
</p>
<p> where we perturb the parameters \(p_1\) and \(p_2\) from \(p_a = (p_1, p_2) = (5, 1)\) to \(p_b = (4.5, 1)\).</p>
<p>Note, that <code>sIpopt</code> has been developed under the constraint that it must work with the regular Ipopt code. Due to this constraint, some compromises had to be made. However, there is an effort to develop <code>sIpopt</code> 2, which is a fork of the Ipopt code that allows for the explicit definition of parametric NLPs. This code can be found at <a href="https://github.com/athrpf/sipopt2">https://github.com/athrpf/sipopt2</a>. If you have questions about <code>sIpopt</code> 2, please contact ​Hans Pirnay.</p>
<h1><a class="anchor" id="INERTIAFREE_CURVTEST"></a>
Inertia-Free Curvature Test</h1>
<p>This section has been contributed by <a href="http://www.mcs.anl.gov/~nychiang/">Nai-Yuan Chiang</a> (Argonne National Laboratory) and <a href="http://zavalab.engr.wisc.edu/">Victor M. Zavala Tejeda</a> (University of Wisconsin-Madison).</p>
<p>In a filter line-search setting it is necessary to detect the presence of negative curvature and to regularize the Hessian of the Lagrangian when such is present. Regularization ensures that the computed step is a descent direction for the objective function when the constraint violation is sufficiently small, which in turn is necessary to guarantee global convergence.</p>
<p>To detect the presence of negative curvature, the default method implemented in IPOPT requires inertia information of the augmented system. The inertia of the augmented system is the number of positive, negative, and zero eigenvalues. Inertia is currently estimated using symmetric indefinite factorization routines implemented in powerful packages such as MA27, MA57, Pardiso, or SPRAL. When more general linear algebra strategies/packages are used (e.g., iterative, parallel decomposition), however, inertia information is difficult (if not impossible) to obtain.</p>
<p>In <a class="el" href="citelist.html#CITEREF_ChiangZavala2014">[2]</a>, we present acceptance tests for the search step that do not require inertia information of the linear system and prove that such tests are sufficient to ensure global convergence. Similar tests were proposed in the exact penalty framework reported in <a class="el" href="citelist.html#CITEREF_CouHubSchWae:inexact">[3]</a>. The inertia-free approach also enables the use of a wider range of linear algebra strategies and packages. We have performed significant benchmarks and found satisfactory performance compared to the inertia-based counterpart. Moreover, we have found that this test can yield significant improvements in computing time because it provides more flexibility to accept steps. This flexibility is particularly beneficial in problems that are inherently ill-conditioned and require significant amounts of regularization.</p>
<p>The inertia-free capability implemented in Ipopt is controlled by the options <a class="el" href="OPTIONS.html#OPT_neg_curv_test_tol">neg_curv_test_tol</a> and <a class="el" href="OPTIONS.html#OPT_neg_curv_test_reg">neg_curv_test_reg</a>. </p>
</div></div><!-- contents -->
</div><!-- PageDoc -->
</div><!-- doc-content -->
</body>
</html>
